<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Block Functions</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
<link rel="home" href="index.html" title="Smarty 3 Manual">
<link rel="up" href="plugins.html" title="Chapter 18. Extending Smarty With Plugins">
<link rel="prev" href="plugins.modifiers.html" title="Modifiers">
<link rel="next" href="plugins.compiler.functions.html" title="Compiler Functions">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr><th colspan="3" align="center">Block Functions</th></tr>
<tr>
<td width="20%" align="left">
<a accesskey="p" href="plugins.modifiers.html">Prev</a> </td>
<th width="60%" align="center">Chapter 18. Extending Smarty With Plugins</th>
<td width="20%" align="right"> <a accesskey="n" href="plugins.compiler.functions.html">Next</a>
</td>
</tr>
</table>
<hr>
</div>
<div class="sect1" title="Block Functions">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="plugins.block.functions"></a>Block Functions</h2></div></div></div>
<div class="funcsynopsis">
<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table">
<tr>
<td><code class="funcdef">void <b class="fsfunc">smarty_block_name</b>(</code></td>
<td>
<var class="pdparam">$params</var>, </td>
<td> </td>
</tr>
<tr>
<td> </td>
<td>
<var class="pdparam">$content</var>, </td>
<td> </td>
</tr>
<tr>
<td> </td>
<td>
<var class="pdparam">$template</var>, </td>
<td> </td>
</tr>
<tr>
<td> </td>
<td>
<var class="pdparam">&amp;$repeat</var><code>)</code>;</td>
<td> </td>
</tr>
</table>
<div class="paramdef-list">
<code>array <var class="pdparam">$params</var></code>;<br><code>mixed <var class="pdparam">$content</var></code>;<br><code>object <var class="pdparam">$template</var></code>;<br><code>boolean <var class="pdparam">&amp;$repeat</var></code>;</div>
<div class="funcprototype-spacer"> </div>
</div>
<p>
     Block functions are functions of the form:
     <code class="literal">{func} .. {/func}</code>. In other words, they enclose a
     template block and operate on the contents of
     this block. Block functions take precedence over
     <a class="link" href="language.custom.functions.html" title="Chapter 8. Custom Functions">custom functions</a> of
     the same name, that is, you cannot have both custom function
     <code class="literal">{func}</code> and block function
     <code class="literal">{func}..{/func}</code>.
    </p>
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
<li class="listitem"><p>
      By default your function implementation is called twice by
      Smarty: once for the opening tag, and once for the closing tag.
      (See <code class="literal">$repeat</code> below on how to change this.)
     </p></li>
<li class="listitem"><p>
      Starting with Smarty 3.1 the returned value of the opening tag call is 
      displayed as well.
     </p></li>
<li class="listitem"><p>
     Only the opening tag of the block function may have
     <a class="link" href="language.syntax.attributes.html" title="Attributes">attributes</a>. All
     attributes passed to template functions from the template are contained
     in the <em class="parameter"><code>$params</code></em> variable as an associative array.
     The opening tag attributes are also accessible to your function
     when processing the closing tag.
    </p></li>
<li class="listitem"><p>
     The value of the <em class="parameter"><code>$content</code></em> variable depends on
     whether your function is called for the opening or closing tag. In case
     of the opening tag, it will be <code class="constant">NULL</code>, and in case of
     the closing tag it will be the contents of the template block.
     Note that the template block will have already been processed by
     Smarty, so all you will receive is the template output, not the
     template source.
    </p></li>
<li class="listitem"><p>
     The parameter <em class="parameter"><code>$repeat</code></em> is passed by
     reference to the function implementation and provides a
     possibility for it to control how many times the block is
     displayed. By default <em class="parameter"><code>$repeat</code></em> is
     <code class="constant">TRUE</code> at the first call of the block-function (the opening tag)
     and <code class="constant">FALSE</code> on all subsequent calls to the block function
     (the block's closing tag).
     Each time the function implementation returns with
     <em class="parameter"><code>$repeat</code></em> being <code class="constant">TRUE</code>, the contents between
     <code class="literal">{func}...{/func}</code> are evaluated and the function
     implementation is called again with the new block contents in the parameter
     <em class="parameter"><code>$content</code></em>.
	</p></li>
</ul></div>
<p>
     If you have nested block functions, it's possible to find out what the
     parent block function is by accessing
     <code class="literal">$smarty-&gt;_tag_stack</code> variable. Just do a
     <a class="ulink" href="http://php.net/var_dump" target="_top"><code class="varname">var_dump()</code></a>
     on it and the structure should be apparent.
    </p>
<div class="example">
<a name="id464482"></a><p class="title"><b>Example 18.5. block function</b></p>
<div class="example-contents"><pre class="programlisting">

&lt;?php
/*
 * Smarty plugin
 * -------------------------------------------------------------
 * File:     block.translate.php
 * Type:     block
 * Name:     translate
 * Purpose:  translate a block of text
 * -------------------------------------------------------------
 */
function smarty_block_translate($params, $content, Smarty_Internal_Template $template, &amp;$repeat)
{
    // only output on the closing tag
    if(!$repeat){
        if (isset($content)) {
            $lang = $params['lang'];
            // do some intelligent translation thing here with $content
            return $translation;
        }
    }
}
?&gt;

     </pre></div>
</div>
<br class="example-break"><p>
 See also:
 <a class="link" href="api.register.plugin.html" title="registerPlugin()"><code class="varname">registerPlugin()</code></a>,
 <a class="link" href="api.unregister.plugin.html" title="unregisterPlugin"><code class="varname">unregisterPlugin()</code></a>.
</p>
</div>
<div class="navfooter">
<hr>
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left">
<a accesskey="p" href="plugins.modifiers.html">Prev</a> </td>
<td width="20%" align="center"><a accesskey="u" href="plugins.html">Up</a></td>
<td width="40%" align="right"> <a accesskey="n" href="plugins.compiler.functions.html">Next</a>
</td>
</tr>
<tr>
<td width="40%" align="left" valign="top">Modifiers </td>
<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
<td width="40%" align="right" valign="top"> Compiler Functions</td>
</tr>
</table>
</div>
</body>
</html>
